doc: clarify that features cannot be both experimental and deprecated#62456
doc: clarify that features cannot be both experimental and deprecated#62456aduh95 wants to merge 2 commits intonodejs:mainfrom
Conversation
|
Review requested:
|
|
Shouldn't there be some way to provide advanced warning? |
wdym? Do you have a scenario in mind? |
| * An improved alternative API is available. | ||
| * Breaking changes to the API are expected in a future major release. | ||
|
|
||
| Deprecated features are subject to [semantic versioning][] rules. |
There was a problem hiding this comment.
I don't think this is the case for the undocumented features being deprecated.
doc/api/documentation.md
Outdated
| > | ||
| > Experimental features leave the experimental status typically either by | ||
| > graduating to stable, or are removed without a deprecation cycle. | ||
| > graduating to stable, by being deprecated, or are removed without a deprecation cycle. |
There was a problem hiding this comment.
Clarifying question: does this mean #62395 (comment) can land because it's doing exactly the newly added exit condition? That is the transition of stability index can be:
- 1 -> 2: stable
- 1 -> 0: deprecated
- 1 -> (black hole?): removed
|
|
|
Changes in |
|
I don't think undocumented features are much different from experimental ones, we don't bother going through a deprecation cycle for those – or when we do, we're putting it back into semver as we sorta guarantee it won't be removed until the end of the deprecation cycle. I'm failing to see the nuance where we can get away with a breaking change to an API yet we would deprecate it.
I'd rather not, IMO it only makes sense to land both or none. |
There was a problem hiding this comment.
I generally agree with this, but guidance or specific solution (eg Joyee's suggestion of "pending removal") is needed to clarify how to handle what we would otherwise call deprecation of an experimental feature. I'm not saying we need a deprecation cycle, but we need some avenue available that allows us to gently inform users (a runtime deprecation is not that).
As-is, this handcuffs a considerate user experience with what feels like "not my problem". I'm not saying that's your intention, but it does leave us wondering "well, what do we do now…".
There was a problem hiding this comment.
Unfortunately we had a few experimental feature that have been kept going forever and they are widely adopted because they are the only way to do things. (async_hooks, looking at you, but also others).
This is change would be correct in principle, but it would require us to revise what we have as experimental, and move what we cannot safely remove to stable (again, looking at you, async_hooks).
|
@JakobJingleheimer @mcollina you guys approved #62395 but are blocking this PR. That seems paradoxical, the goal of this PR was to enable #62395, so I don't follow the reasoning. Is it that you think #62395 should be an exception outside of the documented process, or you disagree with the interpretation that is made in this PR? Regarding async_hooks, I don't agree with your analysis, we're unlikely to deprecate/remove the whole of async_hooks any time soon; if we have to remove a subset of it (with non-zero user-adoption), this PR says we can deprecate that subset and avoid breaking it until it's completely removed, which AFAIK is already the status quo. Regarding adding a new "sub-status" for experimental features pending removal, I'm certainly not against it (I'm the one who suggested it in #62395 (comment)); that being said, in the TSC meeting, deprecation seemed to be preferred, or at least that's what the discussion revolved around. That PR somewhat removes the need for that "pending removal" status, though does not conflicts with it, if someone wants to work on that. |
|
It sounds to me like this is saying things now go from experimental directly to runtime deprecation with no "gentle" step in between. My objection is the missing middle step (where appropriate). Or do I just not understand what the new language is saying?
Ack, sorry to misremember/misattribute. |
Hum this says nothing about runtime deprecation, only deprecation (which typically starts as doc-only). |
|
As far as I can tell the only change in policy that this PR makes is that once something is deprecated, any further changes need to follow semver. I think part of the confusion is around what the implications are of that change, which aren’t spelled out. For example:
I don’t know from reading this PR what the answers are to these questions. |
8 participants
As discussed in the TSC meeting. The rationale is that either an experimental feature can be called experimental only if breaking changes (incl removal) would not break the ecosystem; if removing an experimental feature must go through a deprecation cycle, it is de facto no-longer experimental.